home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 3.iso / dist / fw_plotutils.idb / usr / freeware / catman / u_man / cat1 / spline.Z / spline
Encoding:
Text File  |  2002-01-08  |  14.2 KB  |  397 lines
  1.  
  2.  
  3.  
  4. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        spline -    interpolate datasets using splines under tension
  9.  
  10. SSYYNNOOPPSSIISS
  11.        sspplliinnee [    _o_p_t_i_o_n_s    ] [ _f_i_l_e_s ]
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.        sspplliinnee  reads  datasets from standard input or from one or
  15.        more files, and fits a smooth curve (a  "spline")  through
  16.        each  dataset.    An  interpolated version of each dataset,
  17.        consisting of points from the smooth curve, is written  to
  18.        standard    output.
  19.  
  20.        Unless  the  --aa    or  --AA options are used    (see below), each
  21.        dataset should be a sequence of values for a vector-valued
  22.        function     of  a    single    scalar    variable.   That is, each
  23.        dataset should be a sequence  of     data  points,    given  as
  24.        alternating  _t  and  _y  values.    _t is a scalar independent
  25.        variable, and _y is  a  vector-valued  dependent    variable.
  26.        The  dimensionality  of    _y is specified with the    --dd option
  27.        (the default dimensionality  is    1).   Between  each  data
  28.        point and the next, _t should increase.
  29.  
  30.        An  input file may contain more than a single dataset.  If
  31.        an input    file  is  in  ASCII  format  (the  default),  its
  32.        datasets     should    be separated by    blank lines.  The _t and    _y
  33.        values of the data points in each dataset may be     arranged
  34.        arbitrarily, so long as they are    separated by white space.
  35.        Besides datasets, an input file may contain any number  of
  36.        comment lines, which should begin with the comment charac
  37.        ter `#'.     Comment lines are ignored.  They are not treated
  38.        as  blank,  i.e.,  they    do  not     interrupt  a  dataset in
  39.        progress.
  40.  
  41.        Options and file    names may be interspersed on the  command
  42.        line,  but the options are processed before the file names
  43.        are read.  If ----    is seen, it is interpreted as the end  of
  44.        the  options.  If no file names are specified, or the file
  45.        name -- is encountered, the standard input is read.
  46.  
  47.        The type    of interpolation, and the format of the    input and
  48.        output files, may be selected by    command-line options.
  49.  
  50. OOPPTTIIOONNSS
  51.    IInntteerrppoollaattiioonn--RReellaatteedd OOppttiioonnss
  52.        --ff
  53.        ----ffiilltteerr
  54.           Use  a  local  interpolation  algorithm  (the cubic
  55.           Bessel algorithm), so that sspplliinnee    can be used as    a
  56.           real-time     filter.   The slope of    the interpolating
  57.           curve at each point in a dataset will be chosen  by
  58.           fitting a    quadratic function through that    point and
  59.           the two adjacent points in the dataset.  If  --ff  is
  60.           specified     then  the --tt option, otherwise    optional,
  61.  
  62.  
  63.  
  64. FSF                 Dec 1998                1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  71.  
  72.  
  73.           must be used as well.  Also,  if    --ff  is    specified
  74.           then the --kk, --pp, and --TT options may not be used.
  75.  
  76.           If  --ff  is _n_o_t specified,    then the default (global)
  77.           interpolation algorithm will be used.
  78.  
  79.        --kk _k
  80.        ----bboouunnddaarryy--ccoonnddiittiioonn _k
  81.           Set the boundary condition parameter for each  con
  82.           structed    spline    to  be    _k.  (The default value is
  83.           1.0.)  In    each of    its components,    the  spline  will
  84.           satisfy  the  two     boundary conditions y"[0]=ky"[1]
  85.           and y"[n]=ky"[n-1].  Here    y[0] and y[1] signify the
  86.           values  of a specified component of the vector-val
  87.           ued dependent variable _y at the first two    points of
  88.           a     dataset,  and    y[n-1] and y[n]    the values at the
  89.           last two points.    Setting    _k to zero  will     yield    a
  90.           "natural"    spline,    i.e., one that has zero    curvature
  91.           at the two ends of the dataset.  The --kk option  may
  92.           not be used if --ff    or --pp is specified.
  93.  
  94.        --nn _n
  95.        ----nnuummbbeerr--ooff--iinntteerrvvaallss _n
  96.           Subdivide     the  interval    over  which interpolation
  97.           occurs into _n subintervals.   The     number     of  data
  98.           points computed, and written to the output, will be
  99.           _n_+_1.  The    default    value for _n is 100.
  100.  
  101.        --pp
  102.        ----ppeerriiooddiicc
  103.           Construct    a periodic spline.   If     this  option  is
  104.           specified,  the  _y  values  for  the first and last
  105.           points in    each dataset must be equal.  The  --ff  and
  106.           --kk options may not be used if --pp is specified.
  107.  
  108.        --TT _t_e_n_s_i_o_n
  109.        ----tteennssiioonn _t_e_n_s_i_o_n
  110.           Each  interpolating  curve  will    be a spline under
  111.           tension.    This option sets the tension  value  (the
  112.           default is 0.0).
  113.  
  114.           If  _t_e_n_s_i_o_n equals zero, the curve will be a piece
  115.           wise cubic spline.  Increasing  the  tension  above
  116.           zero  makes  the    curve  "tighter", and reduces the
  117.           likelihood of spurious inflection    points.     That  is
  118.           because between each pair    of successive points in    a
  119.           dataset, the curve will  satisfy    the  fourth-order
  120.           differential                 equation
  121.           y""=sgn(_t_e_n_s_i_o_n)*(_t_e_n_s_i_o_n^2)y" in    each of    its  com
  122.           ponents.     As  _t_e_n_s_i_o_n increases to positive infin
  123.           ity, it will converge to a polygonal line.  The  --TT
  124.           option may not be    used if    --ff is specified.
  125.  
  126.  
  127.  
  128.  
  129.  
  130. FSF                 Dec 1998                2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  137.  
  138.  
  139.        --tt _t_m_i_n _t_m_a_x _[_t_s_p_a_c_i_n_g_]
  140.        ----tt--ssppaacciinngg _t_m_i_n    _t_m_a_x _[_t_s_p_a_c_i_n_g_]
  141.           For  each     dataset,  set    the  interval  over which
  142.           interpolation occurs to  be  the    interval  between
  143.           _t_m_i_n  and     _t_m_a_x.    If _t_s_p_a_c_i_n_g is not specified, the
  144.           interval will be divided into the    number of  subin
  145.           tervals specified    by the --nn option.
  146.  
  147.           If  the  --tt  option  is not used,    the interval over
  148.           which interpolation occurs will be the entire range
  149.           of the independent variable in the dataset.  The --tt
  150.           option must always be used if the    --ff option is used
  151.           to request filter-like behavior (see above).
  152.  
  153.    FFoorrmmaatt--RReellaatteedd OOppttiioonnss
  154.        --dd _d_i_m_e_n_s_i_o_n
  155.        ----yy--ddiimmeennssiioonn _d_i_m_e_n_s_i_o_n
  156.           Set  the dimensionality of the dependent variable    _y
  157.           in the input and output files to be _d_i_m_e_n_s_i_o_n.  The
  158.           default dimension    is 1.
  159.  
  160.        --II _d_a_t_a_-_f_o_r_m_a_t
  161.        ----iinnppuutt--ffoorrmmaatt _d_a_t_a_-_f_o_r_m_a_t
  162.           Set  the    data  format  for the input file(s) to be
  163.           _d_a_t_a_-_f_o_r_m_a_t, which may be    one of the following.
  164.  
  165.           aa         ASCII format (the default).  Each file is    a
  166.              sequence  of  floating point numbers, inter
  167.              preted as the _t and  _y  coordinates  of  the
  168.              successive     data  points in a dataset.  If    _y
  169.              is    _d-dimensional, there will be _d_+_1  numbers
  170.              for  each point.  The _t and _y coordinates of
  171.              a point need not appear on     the  same  line,
  172.              and  points  need    not  appear  on    different
  173.              lines.  But if a blank  line  occurs  (i.e.,
  174.              two  newlines in succession are seen), it is
  175.              interpreted as the    end of a dataset, and the
  176.              beginning of the next.
  177.  
  178.           ff         Single  precision    binary format.    Each file
  179.              is    a sequence  of    floating  point     numbers,
  180.              interpreted  as  the  _t and _y coordinates of
  181.              the successive data points    in a dataset.  If
  182.              _y    is  _d-dimensional, there will be _d_+_1 num
  183.              bers for each  point.   Successive     datasets
  184.              are  separated by a single    occurrence of the
  185.              quantity FLT_MAX, which is    the largest  pos
  186.              sible  single  precision floating point num
  187.              ber.  On most machines this is approximately
  188.              3.4x10^38.
  189.  
  190.           dd         Double  precision    binary format.    Each file
  191.              is    a sequence of double  precision     floating
  192.              point  numbers,  interpreted  as the _t and    _y
  193.  
  194.  
  195.  
  196. FSF                 Dec 1998                3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  203.  
  204.  
  205.              coordinates of the    successive data    points in
  206.              a    dataset.   If  _y  is _d-dimensional, there
  207.              will be _d_+_1 numbers for each point.  Succes
  208.              sive  datasets  are  separated  by     a single
  209.              occurrence    of the quantity    DBL_MAX, which is
  210.              the largest possible double precision float
  211.              ing point number.    On most    machines this  is
  212.              approximately 1.8x10^308.
  213.  
  214.           ii         Integer  binary  format.    Each  file  is    a
  215.              sequence of integers, interpreted as  the    _t
  216.              and  _y  coordinates  of  the successive data
  217.              points in a dataset.  If _y    is _d-dimensional,
  218.              there  will  be  _d_+_1 numbers for each point.
  219.              Successive    datasets are separated by a  sin
  220.              gle  occurrence  of  the  quantity     INT_MAX,
  221.              which is the largest possible  integer.   On
  222.              most machines this    is 2^31-1.
  223.  
  224.        --aa _[_s_t_e_p___s_i_z_e _[_l_o_w_e_r___l_i_m_i_t_]_]
  225.        ----aauuttoo--aabbsscciissssaa _[_s_t_e_p___s_i_z_e _[_l_o_w_e_r___l_i_m_i_t_]_]
  226.           Automatically  generate  values for _t, the indepen
  227.           dent variable (the default values    of _s_t_e_p___s_i_z_e  and
  228.           _l_o_w_e_r___l_i_m_i_t are 1.0 and 0.0, respectively).
  229.  
  230.           Irrespective  of    data  format  (`a',  `f', `d', or
  231.           `i'), this option    specifies that the  values  of    _t
  232.           are  missing from    the input file:    the dataset(s) to
  233.           be read contain only values  of  _y,  the    dependent
  234.           variable.      So if    _y is _d-dimensional, there will be
  235.           only _d numbers for each point.  The increment  from
  236.           each _t value to the next will be _s_t_e_p___s_i_z_e, and the
  237.           first _t value will be _l_o_w_e_r___l_i_m_i_t.  This option  is
  238.           useful, e.g., when interpolating curves rather than
  239.           functions.
  240.  
  241.        --AA
  242.        ----aauuttoo--ddiisstt--aabbsscciissssaa
  243.           Automatically generate values for    _t,  the     indepen
  244.           dent  variable.    This  is a variant form    of the --aa
  245.           option.  The increment from each    _t  value  to  the
  246.           next  will  be  the distance in _d-dimensional space
  247.           between the corresponding    _y values, and the first    _t
  248.           value  will  be 0.0.  That is, _t will be "polygonal
  249.           arclength".  This    option is useful when interpolat
  250.           ing curves rather    than functions.
  251.  
  252.        --OO _d_a_t_a_-_f_o_r_m_a_t
  253.        ----oouuttppuutt--ffoorrmmaatt _d_a_t_a_-_f_o_r_m_a_t
  254.           Set the data format for the output file to be _d_a_t_a_-
  255.           _f_o_r_m_a_t.  The interpretation of _d_a_t_a_-_f_o_r_m_a_t  is  the
  256.           same  as    for  the  --II option.  The default is `a',
  257.           i.e., ASCII format.
  258.  
  259.  
  260.  
  261.  
  262. FSF                 Dec 1998                4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  269.  
  270.  
  271.        --PP _s_i_g_n_i_f_i_c_a_n_t_-_d_i_g_i_t_s
  272.        ----pprreecciissiioonn _s_i_g_n_i_f_i_c_a_n_t_-_d_i_g_i_t_s
  273.           Set the numerical    precision for the _t and    _y  values
  274.           in  the output file to be    _s_i_g_n_i_f_i_c_a_n_t_-_d_i_g_i_t_s.  This
  275.           takes effect only    if the output file is written  in
  276.           `a'  format,  i.e.,  in  ASCII.  _s_i_g_n_i_f_i_c_a_n_t_-_d_i_g_i_t_s
  277.           must be a    positive integer (the default is 6).
  278.  
  279.        --ss
  280.        ----ssuupppprreessss--aabbsscciissssaa
  281.           Omit the independent variable  _t    from  the  output
  282.           file;  for  each    point,    supply only the    dependent
  283.           variable _y.  If _y    is _d-dimensional, there     will  be
  284.           only  _d  numbers    for  each  point,  not _d_+_1.  This
  285.           option is    useful when interpolating  curves  rather
  286.           than functions.
  287.  
  288.    IInnffoorrmmaattiioonnaall OOppttiioonnss
  289.        ----hheellpp Print a list of command-line options, and    exit.
  290.  
  291.        ----vveerrssiioonn
  292.           Print the    version    number of sspplliinnee and the plotting
  293.           utilities    package, and exit.
  294.  
  295. EEXXAAMMPPLLEESS
  296.        Typing
  297.  
  298.           eecchhoo 00 00 11 11 22 00 || sspplliinnee
  299.  
  300.        will produce on standard    output    an  interpolated  dataset
  301.        consisting  of 101 data points.    If graphed, this interpo
  302.        lated dataset will yield    a parabola.
  303.  
  304.        It is sometimes useful to interpolate between  a     sequence
  305.        of arbitrarily placed points in _d-dimensional space, i.e.,
  306.        to "spline a curve" rather than a function.  The    --aa and --ss
  307.        options are used    for this.  For example,
  308.  
  309.           eecchhoo 00 00 11 00 11 11 00 11 || sspplliinnee --dd 22 --aa --ss
  310.  
  311.        will  produce  on standard output a 101-point dataset that
  312.        interpolates between the    four points (0,0), (1,0),  (1,1),
  313.        and  (0,1).   The --dd 22 option specifies that the    dependent
  314.        variable    _y is two-dimensional.  The  --aa    option    specifies
  315.        that the    _t values are missing from the input and    should be
  316.        automatically generated.     The --ss    option specifies that the
  317.        _t values    should be stripped from    the output.
  318.  
  319. AAUUTTHHOORRSS
  320.        sspplliinnee  was  written  by     Robert     S.  Maier (rrssmm@@mmaatthh..aarrii
  321.        zzoonnaa..eedduu), starting with    an earlier version by  Rich  Mur
  322.        phey  (rriicchh@@ffrreeeebbssdd..oorrgg).  The algorithms for constructing
  323.        splines under tension are similar to  those  used  in  the
  324.        FITPACK subroutine library, and are ultimately due to Alan
  325.  
  326.  
  327.  
  328. FSF                 Dec 1998                5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. SPLINE(1)          GNU Plotting Utilities        SPLINE(1)
  335.  
  336.  
  337.        K. Cline    (cclliinnee@@ccss..uutteexxaass..eedduu).
  338.  
  339. SSEEEE AALLSSOO
  340.        "The GNU    Plotting Utilities Manual".
  341.  
  342. BBUUGGSS
  343.        Email bug reports to bbuugg--ggnnuu--uuttiillss@@ggnnuu..oorrgg.
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394. FSF                 Dec 1998                6
  395.  
  396.  
  397.